|
|||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||
See:
Description
| Packages | |
| javax.wireless.messaging | Provides classes and interfaces as specified in the WMA 2.0 specification. |
The messaging API is based on the Generic Connection Framework (GCF), which
is defined in the Connected Limited Device Configuration (CLDC) 1.0 specification.
The package javax.microedition.io defines the framework and supports
input/output and networking functionality in J2ME profiles. It provides a coherent
way to access and organize data in a resource-constrained environment.
The design of the messaging functionality is similar to the datagram functionality that is used for UDP in the Generic Connection Framework. Like the datagram functionality, messaging provides the notion of opening a connection based on a string address and that the connection can be opened in either client or server mode. However, there are differences between messages and datagrams, so messaging interfaces do not inherit from datagram. It might also be confusing to use the same interfaces for messages and datagrams.
The interfaces for the messaging API have been defined in the
javax.wireless.messaging
package.
A message can be thought of as having an address part and a data part. A message
is represented by a class that implements the interface defined for messages
in the API. This interface provides methods that are common for all messages.
In the javax.wireless.messaging package, the base interface that
is implemented by all messages is named Message. It provides methods
for addresses and timestamps.
For the data part of the message, the API is designed to handle text,
binary and multipart messages. These are represented by three subinterfaces of Message:
TextMessage, BinaryMessage and MultipartMessage. These subinterfaces
provide ways to manipulate the payload of the message as Strings, byte arrays and message parts,
respectively.
Other subinterfaces of Message can be defined for message payloads
which are neither pure text nor pure binary. It is also possible to create further
subinterfaces of TextMessage, BinaryMessage and MultipartMessage for
possible protocol-specific features.
As defined by the Generic Connection Framework, the message sending and receiving
functionality is implemented by a Connection interface, in this
case, MessageConnection. To make a connection, the application
obtains an object implementing the MessageConnection from the Connector
class by providing a URL connection string that identifies the address.
If the application specifies a full destination address that defines a recipient
to the Connector, it gets a MessageConnection that
works in a "client" mode. This kind of Connection can
only be used for sending messages to the address specified when creating it.
The application can create a "server" mode MessageConnection
by providing a URL connection string that includes only an identifier that specifies
the messages intended to be received by this application. Then it can use this
MessageConnection object for receiving and sending messages.
The format of the URL connection string that identifies the address is specific to the messaging protocol used.
For sending messages, the MessageConnection object provides factory
methods for creating Message objects. For receiving messages, the
MessageConnection supports an event listener-based receiving mechanism,
in addition to a synchronous blocking receive() method. The methods
for sending and receiving messages can throw a SecurityException
if the application does not have the permission to perform these operations.
The generic connection framework includes convenience methods for getting
InputStream and OutputStream handles for
connections which are StreamConnections. The
MessageConnection does not support stream based operations.
If an application calls the Connector.open*Stream
methods, it will receive an IllegalArgumentException.
The basic MessageConnection and Message
framework provides a general mechanism with establishing a
messaging application.
The appendices describe the specific adapter requirements
for URL connection string formatting and bearer-specific
message handling requirements.
The appendices of this specification include the definition of SMS, CBS and MMS URL connection strings. These connection schemes MAY be reused in other adapter specifications, as long as the specified syntax is not modified and the usage does not overlap with these specified adapters (that is, no platform can be expected to implement two protocols for which the URI scheme would be the same, making it impossible for the platform to distinguish which is desired by the application). Other adapter specifications MAY define new connection schemes, as long as these do not conflict with any other connection scheme in use with the Generic Connection Framework.
The appendices describe how the SMS, CBS and MMS adpaters MUST be implemented to conform to the requirements of their specific wireless network environments and how these adapters supply the functionality defined in the javax.wireless.messaging package.
When a GSM SMS message connection is established, the platform MUST use the rules in Appendix A for the syntax of the URL connection string and for treatment of the message contents.
When a GSM CBS message connection is established, the platform MUST use the rules in Appendix B for the syntax of the URL connection string and for treatment of the message contents.
When a CDMA SMS message connection is established, the platform MUST use the rules in Appendix C for the syntax of the URL connection string and for treatment of the message contents.
When a MMS message connection is established, the platform MUST use the rules in Appendix D for the syntax of the URL connection string and for treatment of the message contents.
To send and receive messages using this API, applications MUST be granted a permission to perform the requested operation. The mechanisms for granting a permission are implementation dependent.
The permissions for sending and receiving MAY depend on the type of messages and addresses being used. An implementation MAY restrict an application's ability to send some types of messages and/or sending messages to certain recipient addresses. These addresses can include device addresses and/or identifiers, such as port numbers, within a device.
An implementation MAY restrict certain types of messages or connection addresses, such that the permission would never be available to an application on that device.
The applications MUST NOT assume that successfully sending one message implies that they have the permission to send all kinds of messages to all addresses.
An application should handle SecurityExceptions when a connection
handle is provided from Connector.open(url) and for
any message receive() or send()
operation that potentially engages with the network or the
privileged message storage on the device.
When the JSR 205 interfaces are deployed on a MIDP 1.0 device, there is no
formal mechanism to identify how a permission to use a specific feature can
be granted to a running application. On some systems, the decision to permit
a particular operation is left in the hands of the end user. If the user decides
to deny the required permission, then a SecurityException can be
thrown from the Connector.open(), the MessageConnection.send(),
or the MessageConnection.receive() method.
When the JSR 205 interfaces are deployed on a MIDP 2.0 device, permissions must be granted to open a connection and to send and receive messages. Separate permissions are provided for the SMS and CBS protocols.
To open a connection, a MIDlet suite must have the appropriate permission to access the MessageConnection implementation. If the permission is not granted, then Connector.open must throw a SecurityException. To send and receive messages, the MIDlet suite can restrict certain types of messages or connection addresses. If the application attempts to send or receive either a restricted type of message or a message with a restricted connection address, then a SecurityException must be thrown.
For more information on the permissions that are provided by WMA 2.0, see Appendix E "Deploying JSR 205 Interfaces on a MIDP 2.0 Platform".
This section provides some examples of how the messaging API can be used.
The following sample code sends the string "Hello World!" to an end user as a normal SMS message.
try {
String addr = "sms://+358401234567";
MessageConnection conn = (MessageConnection) Connector.open(addr);
TextMessage msg =
(TextMessage)conn.newMessage(MessageConnection.TEXT_MESSAGE);
msg.setPayloadText("Hello World!");
conn.send(msg);
} catch (Exception e) {
...
}
The following sample code illustrates a server application that waits for
messages sent to port 5432 and responds to them.
try {
String addr = "sms://:5432";
MessageConnection conn = (MessageConnection) Connector.open(addr);
Message msg = null;
while (someExitCondition) {
// wait for incoming messages
msg = conn.receive();
// received a message
if (msg instanceof TextMessage) {
TextMessage tmsg = (TextMessage)msg;
String receivedText = tmsg.getPayloadText();
// respond with the same text with "Received:"
// inserted in the beginning
tmsg.setPayloadText("Received:" + receivedText);
// Note that the recipient address in the message is
// already correct as we are reusing the same object
conn.send(tmsg);
} else {
// Received message was not a text message, but e.g. binary
...
}
}
} catch (Exception e) {
...
}
|
|||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||